**************************************************************************

		McAssemblyª V7.4 Shareware DocsÊ
		Copyright © 1986,87 By Signature Software

**************************************************************************
(This document is layed out for Monaco 9, with tabs set to eight spaces.)

**************************************************************************
			CHANGES IN VERSION 7.4
**************************************************************************

* McAssembly is now "MultiFinder-friendly". This means two things:
	1.) McAssembly's SIZE -1 resource is compatible with MultiFinder
		and indicates to MF that McAssembly is "MF-aware". If you
		find yourself running out of symbol table space when running
		under MF, then increase the minimum and preferred sizes in
		the SIZE -1 resource.
	2.) McAssembly can run in the background under MF. This means that
		you can run assemblies, links, and jobs as a background
		process.

**************************************************************************
			CHANGES IN VERSION 7.3
**************************************************************************

* The trap compiler now supports the new 256K ROM (color) traps.

**************************************************************************
			CHANGES IN VERSION 7.2
**************************************************************************

* Fixed a bug in macro substrings - if substring length was longer than the
	actual parameter string and if the substring didn't start in the
	first position, then garbage was added to the string when it was
	expanded.

**************************************************************************
			CHANGES IN VERSION 7.1
**************************************************************************

* Fixed a bug in the linker - included resources which had an odd length
	were getting their fourth byte zapped to zero.

**************************************************************************
			CHANGES IN VERSION 7.0
**************************************************************************

* The assembler now supports 68010, 68020, and 68851 instructions.

**************************************************************************
			CHANGES IN VERSION 6.9
**************************************************************************

* STR resources with ID's greater than 999 are now used to build the Transfer
	menu. This allows you to make your own transfer menu.
* Raw data files can now have their types and signatures specified with
	FTYPE and FSIGN.
* BTST's are now allowed on PC-relative operands.
* MOVE An,CCR is now illegal.
* The linker's maximum resource size has been increased from 32K to 64K.

**************************************************************************
			CHANGES IN VERSION 6.8
**************************************************************************

* Added the ability to combine multiple user-defined resource module files
	into one resource in the linker.

**************************************************************************
			CHANGES IN VERSION 6.7
**************************************************************************

* The status window is now moveable.
* The main and status windows are now moveable across all of a large screen
	display.
* Save Options now also saves the sizes and locations of both windows.

**************************************************************************
			CHANGES IN VERSION 6.6
**************************************************************************

* Added the Print to Modem Port option in Misc. menu.
* RSEC now takes an origin as in:   RSEC <orgexpr> [,An].

**************************************************************************
			INTRODUCTION
**************************************************************************

	This document briefly describes the McAssembly program - an assembler, 
resource compiler, linker, and job controller for the Macintosh. McAssembly is 
a shareware program - if you like it and use it, then please register it by 
sending $50.00 to:

	Signature Software (checks payable to same)
	2151 Brown Ave.
	Bensalem, PA 19020		(215) 639-8764

All registered owners will receive the following:
	¥ a 94-page manual
	¥ the latest version of the program
	¥ Apple's EDIT editor
	¥ a symbolic debugger called McBug
	¥ several example working applications source code files
	¥ all of the standard Apple equate, trap, and .rel files in McAssembly
		format (MPW Version 2.0 or later)
	¥ a utility to convert McAssembly .rel files to MDS .rel files
	¥ 24-hour, 7-day telephone support
	(Supplied on two 400K MFS diskettes. All of the source and equate
	files are in a packed format to conserve disk space. An unpacking
	utility is provided.)

	I strongly recommend that you register it if you use it, just for the 
additional examples and manual alone. (This document must of necessity be very 
brief - the manual goes into much greater detail. The WriteNow manual files are 
over 400K, which I thought was too much to expect people to download, so I've 
condensed them into this text file.)

	To those of you who might object that this isn't a complete package 
because I've not distributed everything that you should have (particularly the 
system equate files and examples), I answer as follows:

	¥ The whole package takes up almost 800K of disk space - I can't 
imagine anyone seriously wanting to download that! The $50.00 registration fee 
is probably a wash when you consider the download charges, the time to download 
and print the docs, and the aggravation. The documentation presented here, 
while condensed, does represent all of the essential information that you need 
to know to use the program, it's just a lot easier if you have the whole 
package. In addition, don't forget that the whole package is a complete 
assembly language development system. Something as complex as that hardly lends 
itself to electronic distribution. In fact, I think I've done a masterful job 
just in getting all of the information you need to use it in only this 50K 
file.

	¥ Parts of the package are copyright by Apple Computer, and I can't 
distribute them indiscriminately. I can supply them to registerees under the 
terms of my license with Apple.

	¥ If you're an experienced Mac assembly language programmer, then the 
information presented here is probably more than enough to get you going. If 
you're converting from some other assembler to McAssembly, you may not even 
need the whole package (although I would still expect you to register.) If 
you're an inexperienced Mac programmer, then the examples in the registered 
package, the system files, and my telephone support would probably be of value 
to you, but I don't see how anyone could object to paying for those.

	¥ Given the current registration ratios of other Macintosh shareware 
programs, what's wrong with having a little incentive to register?


				____________________________________
				|				   |
				|  Dave McWherter	9/3/86     |
				|                                  |
				|  Compuserve 70057,1612           |
				|  Delphi     DMcWherter           |
				|  Genie      D.McWherter          |
				|__________________________________|


**************************************************************************
			THE MENU SELECTIONS
**************************************************************************

	First, a description of the menu options:

	File menu:
		Assemble	assembles a file
		Link		links a group of files
		Run job		executes a .job file
		Save options	save current McAssembly options
		Quit		what else?

	Assembler menu:
		Object file		creates a .rel object file
		Listing to printer	echoes output to printer
		Listing to screen	echoes output to screen
		Listing to file		echoes output to .lst file
		Errors only listing	only outputs error lines
		Symbol table		outputs symbol table at end
		Cross reference		outputs cross reference table at end
		Terse cref mode		removes unref'ed .PSM symbols from 	
					cross reference list
		.PSM file		creates a .PSM file
		DEF all symbols		DEFs all non-.PSM symbols in the file
		No listing headers	suppresses headers in listings
		MPW object format	object file will be in MPW format, .o
		Error lines to clip	copies error lines to clipboard

	Linker menu:
		Symbol table		outputs symbol table at end
		.MAP file output	echoes output to .map file
		Printer output		echoes output to printer
		McBug .SYM file		creates symbol file for use with McBug
		Raw code data file	puts output code in data fork of file
						with no resource formatting
		User .MAP file		creates a .map file in a user-defined
						format

	Jobs menu:
		Stop if Asm error	stop the job if assembly error occurs
		No link if Asm error	don't link if assembly error occurs
		Force assemblies	force all files in job to be assembled

	Misc. menu:
		Enable Beep		enable beep at end of commands
		Use .Print driver	route printer output through the driver
					(else goes directly to serial port B)
		Print to modem port	routes printer output to the modem port
					(only if Use .Print driver not enabled)

	Transfer menu:
		default transfer string names which you can change with ResEdit
		Other			transfers to any other program

**************************************************************************
			SOURCE LINE FORMAT
**************************************************************************

	All source code lines must be in the following form:

	[label]	opcode	[operand]	[;] [comment]

	Tabs or spaces separate fields, and >>> only one tab (or space) can 
appear between the opcode field and the operand field <<<. Labels may contain 
up to 100 characters, all of which are significant. Labels may contain 
alphanumeric characters and any of the following characters: _, %, !, @, #, $, 
?, or period. Labels may be suffixed with a colon if desired.

	The semicolon comment designator character is optional in the majority 
of cases. Specifically, if an opcode appears in the line then you can omit the 
semicolon. If a line contains just a label and a comment, then you have to use 
the semicolon.

**************************************************************************
			ARITHMETIC EXPRESSIONS
**************************************************************************

	All arithmetic and logical operations are 32-bit operations. McAssembly 
supports the following operators and special characters.

	+	integer addition
	-	integer subtraction
	/	integer division (32 bits/32 bits = 32 bits)
	*	integer multiplication (32 bits * 32 bits = 32 bits)
	MOD	integer modulus
	SHL	logical shift left (16 SHL 2 = 64)
	<<	same as SHL
	SHR	logical shift right (16 SHR 3 = 2)
	>>	same as SHR
	AND	logical bit AND
	OR	logical bit OR
	XOR	logical bit eXclusive-OR
	NOT	logical bit inverse
	'xxxx'	character constant (1-4 characters, right justified)
	*	current value of program counter
	$	specifies a hexadecimal number
	%	specifies a binary number

		(The following relational operators return true or false;
		 true = $FFFFFFFF and false = 0.)

	<=	less than or equal
	<>	not equal
	>=	greater than or equal
	<	less than
	>	greater than
	=	equal to

	The expression processor uses standard algebraic precedence rules. Use 
parentheses to force precedence.

**************************************************************************
			ALIGNMENT
**************************************************************************

	McAssembly automatically aligns those things that must be on an even 
address (opcodes, variable or constant words and longs, trap words, etc.) by 
putting a zero byte in front of them if necessary. However, labels on 
automatically aligned lines still carry the value of the address before the 
alignment. These may be odd. If this happens, McAssembly warns you with a LABEL 
ON ODD ADDRESS message. If that's what you really wanted, then you can ignore 
the warning. Otherwise, you must change the code accordingly, probably by 
adding an explicit ALIGN pseudo-op, and reassemble.

**************************************************************************
			THE ASSEMBLER PSEUDO-OPS
**************************************************************************

	(These are almost in alphabetical order. In some cases, pseudo-ops 
which are used together are grouped together for description purposes.)


A5OFF	<absolute expr>			specify initial A5 offset
A5SEC					define A5 offset variables
A5END					end an A5SEC
A5REF	<symbol> [, <symbol>, ...]	reference an A5SEC variable

All global data which is to be stored offset from A5 must be defined between 
A5SEC and A5END. You can have as many A5SEC's in a file as you want - the 
linker concatenates them. A5OFF may be used to specify the initial offset below 
A5 for all of your globals, and defaults to $100. A5REF is used to reference A5 
variables which are defined in other modules. Symbols which are defined as A5 
variables don't have to have the '(A5)' suffixed to them. For example:

		a5off	grafSize
		a5sec
	global1	ds.l	1
	global2	ds.w	2
		a5end
		a5ref	external

		move	global1,d0	this is the same as...
		move	global1(a5),d0		this
		move	external,d0	and this is the same as...
		move	external(a5),d0		this

ALIGN	[<expr>]	aligns the PC to a multiple of <expr>, default = 2
.ALIGN	[<expr>]	aligns the PC to a multiple of <expr>, default = 2

BASE	An, <symbol> [,<symbol>, ...]	auto-offsets specified symbols by An
BASE specifies that a symbol is to be offset by the specified address register 
every time you use it For example, if you do this:

		base	a6,sym1,sym2
		move	sym1,d0			then this instruction
		move	sym1(a6),d0		is the same as this one and
		move	sym1(a3),d0		you can override it if you want

BASE	An		auto-offset all subsequently defined symbols by An
ENDB			turn off symbol basing (only necessary if no symbols
				are specified in the BASE operand list)

CASE	turns on case sensitivity

If you don't use CASE, then case in labels is not significant.


DB	<expr> [, <expr>, ...]	define constant bytes at the PC
DC	<expr> [, <expr>, ...]	define constant words at the PC
DC.B	<expr> [, <expr>, ...]	define constant bytes at the PC
DC.L	<expr> [, <expr>, ...]	define constant longs at the PC
DC.W	<expr> [, <expr>, ...]	define constant words at the PC
DL 	<expr> [, <expr>, ...]	define constant longs at the PC
DW 	<expr> [, <expr>, ...]	define constant words at the PC

DCB 	<count>, <value>	define block of <count> bytes of <value>
DCB.B	<count>, <value>	define block of <count> bytes of <value>
DCB.L 	<count>, <value>	define block of <count> longs of <value>
DCB.W 	<count>, <value>	define block of <count> words of <value>
FILL 	<count>, <value>	equivalent to DCB

DEF 	<symbol> [, <symbol>, ...]	externally define symbols
XDEF 	<symbol> [, <symbol>, ...]	externally define symbols

DEF and XDEF are equivalent - they allow symbols in this file to be referenced 
from another file.

DEFALL

Same as DEF'ing every symbol in the file.

DEFINE	"string"		define a string symbol; the symbol may then be
					used anywhere in a source line between
					curly brackets and will cause a string
					replacement before the line is
					assembled. For example:

	hello	define	"goodbye"	if you define hello to be 'goodbye'
		text	"* {hello} *"	then this string will be '* goodbye *'

DSEC 	<absolute expr> [<An]	start dummy section, org'ed at <absolute expr>,
					base all labels inside to An

DSEC	[<symbol>]		end a DSEC, symbol is set to size of the DSEC

RSEC	<absolute expr> [,An]	begin reverse DSEC, org'ed at <absolute expr>,
					optionally BASE all labels inside to An
					(default A6)
ENDR	[<symbol>]		end an RSEC, symbol set to size of the section


DSEC and DEND delimit "dummy sections", which may contain only storage 
allocation statements. No storage is actually allocated for items in a dummy 
section - their primary use is to assign values to record structures. Only 
storage allocation statements are allowed in dummy sections. For example:

		dsec	1
	sym1	ds.b	1	will have a value of 1
	sym2	ds.w	1	will have a value of 2
	sym3	ds.l	1	will have a value of 4
		dend

Dummy sections may also be defined in 'reverse' using RSEC, for example:

		rsec	0
	sym1	ds	0	will have a value of  0
	sym2	ds.w	1	will have a value of -2
	sym3	ds.l	1	will have a value of -6
	sym4	ds.w	1	will have a value of -8
		endr	rsize	rsize will have a value of 8

DS 	<count>		define <count> words of storage at PC
DS.B	<count>		define <count> bytes of storage at PC
DS.L 	<count>		define <count> longs of storage at PC
DS.W 	<count>		define <count> words of storage at PC

BOOLEAN	<count>		same as ds.w (These allow more mnemonic DS's...)
BYTE	<count>		same as ds.b	"	"	"	"
CHAR	<count>		same as ds.w	"	"	"	"
HANDLE	<count>		same as ds.l	"	"	"	"
HDL	<count>		same as ds.l	"	"	"	"
INTEGER	<count>		same as ds.w	"	"	"	"
LONG	<count>		same as ds.l	"	"	"	"
LONGINT	<count>		same as ds.l	"	"	"	"
POINT	<count>		same as ds.l	"	"	"	"
POINTER	<count>		same as ds.l	"	"	"	"
PTR	<count>		same as ds.l	"	"	"	"
RECT	<count>		same as ds.b  8*<count>
VAR	<count>		same as ds.l	"	"	"	"
WORD	<count>		same as ds.w	"	"	"	"


IF 	<absolute expr>		conditional assembly
ELSE				used with IF
ENDI				end an IF clause
ENDIF				end an IF clause
IFDEF	<symbol>		true if symbol defined
IFNDEF	<symbol>		true if symbol undefined
IF1				true if pass 1
IF2				true if pass 2

Conditional assembly control. For example:

		if	0	the expr is not true, so
		<statements>		these statements aren't assembled
		else				(else clauses are optional)
		<statements>		but these statements are
		endi

IFLIST	<expr>			conditional listing control

If the expression is true (the default condition), then conditional assembly 
clauses which aren't assembled will appear in the listing, otherwise they 
won't.

END		end of program (optional)

EQU	<expr>		equate symbol to <expr>
EQU.B	<expr>		equate symbol to <expr>	(equivalent to equ)
EQU.W	<expr>		equate symbol to <expr>	(equivalent to equ)
EQU.L	<expr>		equate symbol to <expr>	(equivalent to equ)

ERROR	"your error message"

Allows user-definable assembly errors.

FSIGN 	<absolute expr>		specify program's Finder file signature
FTYPE 	<absolute expr>		specify program's Finder file type

For example, if you're assembling an application, then:

		ftype	'APPL'
		fsign	'ursg'

Or, if you're assembling a desk accessory to be installed by the Font/DA Mover:

		ftype	'DFIL'
		fsign	'DMOV'

IPATH	"pathname"	specify an HFS path to subsequent include files
INCL	"filename"	include another source file
INCLUDE	"filename"	include another source file

JTBL   	<symbol> [, <symbol>, ...]	specify jump table entries

Any symbol that's referenced from another segment by a Bcc, DBcc, JSR, JMP, 
LEA, or PEA instruction >>> must <<< be specified as a jump table entry.

LINE	[ <char> [ , <count> ] ]	prettyprint a line of chars

Outputs a listing line filled with the specified number of characters. <count> 
defaults to 50, and <char> defaults to '*'.

LIST	<absolute expr>		listing control

If the expression is true (not 0), then subsequent source lines appear in the 
listing, otherwise they won't.


LFRAME	[An]		begin local variable stack frame, and BASE symbols 	
			inside to An (default A6)
ENDL	[<symbol>]	end a LFRAME, symbol is set to size of the frame

LFRAME and ENDL allow local variables which are to be stored on the stack to be 
easily defined. Symbols defined within the frame are automatically BASE'd to 
the specified register so that you don't have to suffix them with '(An)'. For 
example:

		lframe
	local1	integer		will have an a6 offset of -2
	local2	longint		will have an a6 offset of -6
	local3	rect		will have an a6 offset of -14
		endl	lsize	will have a value of 14

	Subroutine_Entry
		link	a6,#-lsize	save stack space for locals
		move	local1,d0	this instruction is the same as...
		move	-2(a6),d0		this one
		...
		unlk	a6		clear locals from stack
		rts			return


LOC			start new local scope block
LOCSYM	<expr>		change local label character
NOLOC			auto-LOC on non-local labels

Local symbols begin with a period and may contain the same cast of characters 
as normal labels. Their scope normally extends from one LOC statement to the 
next LOC statement. This can be changed with the NOLOC statement, which causes 
local symbol scopes to extend from one non-local label to the next non-local 
label. The local symbol prefix character can be changed with the LOCSYM 
statement. For example,

			loc
		.hello	nop		this .hello
			loc
		.hello	nop		is different than this .hello
		.hello	nop		but this .hello causes an error

Or, using NOLOC, and LOCSYM (for MDS compatibility):

			noloc
			locsym	'@'
		goodbye	nop
		@hello	nop		this @hello
		solong	nop
		@hello	nop		is different than this @hello
		@hello	nop		but this @hello causes an error


MACRO	[&1,&2,...,&F]		begin a macro definition
MACROX	[&1,&2,...,&F]		ditto, no auto LOC on call
ENDM				end a macro definition
MEXP 	<absolute expr>		macro expansion control

These control macros. For example, given a macro called test defined as:

		test	macro	&1,&2,&3,&4,&5,&6
			move	&1,d0
			lea	&2,a0
			if	&&3 = "hello"
			nop
			endi
			text	&&4		notice quote enclosure
		lab%5	nop			notice expand as value string
			&6			parameters may be opcodes
			text	"&2[2:3]	param substring [start:length]
			endm

And a call to test like this:

		num	equ	1234
			test	d2,symbol,hello,mikey,num,_Open

Then it would be expanded to the following:

			move	d2,d0
			lea	symbol,a0
			nop
			text	"mikey"
		lab1234	nop
			_Open
			text	"ymb"

MACROs do an automatic LOC on entry so that local symbols inside the macro have 
their own scope. This prevents local symbols inside the macro from conflicting 
with local symbols outside it. MACROX's do not do the LOC - so that you can 
pass local symbols to a macro if you want. MEXP controls whether or not macro 
expansions appear in the listing: they will appear if the expression is true.


M68000		only allow 68000 instructions and addressing modes (this is
			the default mode)
M68010		only allow 68000 and 68010 instructions and addressing modes
M68020		allow 68000, 68010, and 68020 instructions and addressing modes

NAME	<symbol>	specifies the module name (one source file is a module)

PAGE	["title"]	page eject, optionally specifying a page title

PFRAME	[An]		begin parameter stack frame, and BASE symbols inside to 
				An (default A6)
ENDP	[<symbol>]	end a PFRAME, symbol is set to size of the frame

PFRAME and ENDP allow parameters passed on the stack to subroutines to be 
easily defined. For example, suppose you have a subroutine whose Pascal 
definition is:

   FUNCTION  Slush (parm1: LONGINT; parm2: INTEGER; parm3: BOOLEAN) : INTEGER;

Then you could code it in McAssembly as follows:

			pframe
		result	integer		will have an a6 offset of 16
		parm1	longint		will have an a6 offset of 12
		parm2	integer		will have an a6 offset of 10
		parm3	boolean		will have an a6 offset of 8
			endp	psize	will have a value of 10

		Slush	link	a6,#0
			move	parm2,d0	then this is equivalent to
			move	10(a6),d0		to this
			...
			move	d0,result	returns the result
			unlk	a6
			move.l	(sp)+,a0	get return address
			addi.l	#psize-2,sp	clear parameters (leave result)
			jmp	(a0)		and return

Notice that PFRAME automatically allocates space for a stacked return address 
and a stacked linkage register, so you have to do a 'link' instruction on entry 
to the routine if you use PFRAME. The ENDP is optional is you have an LFRAME 
immediately following.


PRMT	"prompt"		display a prompt on the screen
PRTR	"string"		send ctrl string to printer
PSIZE 	<absolute expr>		set listing page size

REF 	<symbol> [, <symbol>, ...]	reference external symbols
XREF 	<symbol> [, <symbol>, ...] 	reference external symbols

REF and XREF are equivalent and allow you to reference symbols which are 
defined in other modules.


REQU	Dn | An | <register symbol>	equate symbol to a register

For example:

		dataptr	requ	a4
			move.l	(dataptr),d0	then this is the same as...
			move.l	(a4),d0			this
		bufptr	equ	dataptr
			move.l	bufptr,d1	and this...
			move.l	a4,d1			is the same as this


RPATH	"pathname"	specify an HFS path for the .rel object file

SET	<expr>		set symbol to value, may be reSET again

STRING	<expr>		set DC.B string formats:
				0 = no length byte prefixes (default)
				else prefix with length bytes

TABS 	<n>		specify listing tab stops every <n> columns

TCOMP			activate the trap compiler (described later)

TERSE			set short listing format (no line numbers, 16 bits of 	
			program counter)


TEXP 	<absolute expr>		text expansion control

If the expression is 0, then only one line of object bytes appears in the 
listing for a TEXT statement. Otherwise all of the bytes generated by the text 
will appear in the listing.

TEXT	[ - | + | # ] "string"		define a text string

'-' sets bit 7 on the last byte of the string. '+' sets bit 7 in every string 
byte (Apple ][ forever!). '#' stuffs a length byte in front of the string. 
(Only one prefix is allowed at a time.) You can use the following escape 
characters in the string:

		/R	carriage return		$0D
		/L	linefeed		$0A
		/"	double quote		$22
		/T	tab			$09
		/E	escape			$1B
		/0	null			$00
		//	slash			$2F
		/F	formfeed		$0C
		/B	backspace		$08
		/$hh	any hex number		$hh
		/'	single quote		$27
		/D	current date
		/S	select short date form
		/U	select unabbreviated long date form
		/A	select abbreviated long date form (the default)

For example:

		text	#"ABC"		generates 05 41 42 43
		text	+"ABC"		generates C1 C2 C3
		text	-"ABC"		generates 41 42 C3
		text	"ABC/T/$21/R"	generates 41 42 43 09 21 0D


TITLE	"string [$] "	specify listing page title, '$' generates a timestamp

TRAPW 	<absolute expr>	define a trap word
OPWORD	<absolute expr>	define a trap word

For example:

	_Open	trapw	$A003
		_Open

**************************************************************************
			STRING DELIMITERS
**************************************************************************

	In all of the above pseudo-op descriptions, strings have been shown 
delimited by double quotes as in "string". However, you may also delimit them 
with single quotes as in 'string'. The only place you can't use single quotes 
as delimiters is in IF comparisons (because then the single quoted item would 
be evaluated as a character constant.)

**************************************************************************
			.PSM FILES
**************************************************************************

	Packed symbol files are binary files containing only symbol 
definitions. They're smaller in size than their text equivalents. This saves 
disk space and speeds up assembly. They also speed up assembly because they're  
read only on the first pass of the assembly. They're not read on the second 
pass. Packed symbol files have a filename suffix of .PSM.

	You can create a file of symbol definitions from any source file. Just 
select the assembler .PSM file option and assemble the file. McAssembly dumps 
all the names of all symbols defined in the file and their values to a .PSM 
file at the end of the assembly.

	You use .PSM files by INCLuding them in your source files.

	Symbols that are defined in more than one INCLuded .PSM file are not 
flagged as multiply defined symbols. The symbol takes the value of the last 
definition of it processed by McAssembly. This allows you to use .PSM files 
containing overlapping symbol definitions without worrying about multiple 
definitions.

**************************************************************************
			THE TRAP COMPILER
**************************************************************************

	McAssembly contains a built-in Trap Compiler which allows certain 
toolbox and O/S traps to be invoked with one line of source code. It eliminates 
much of the drudgery from trap setup and interfacing. For brevity, we'll call 
the Trap Compiler simply the TC throughout the rest of this section.

	The TC was designed to simplify interfacing to the Macintosh 
stack-based traps. Stack-based traps are those traps which pass parameters and 
return results on the 68000 stack. (As opposed to register-based traps, which 
pass parameters and return results in 68000 registers.) Interfacing to 
stack-based traps requires a standard sequence of steps which are common to all 
such traps: 

	1.) If the trap is a function, make room on the stack for the function 	
	result.
	2.) Push the parameters on the stack.
	3.) Execute the trap.
	4.) If the trap is a function, remove the function result from the 	
	stack.

This standard sequence requires a large amount of source code overhead each 
time a trap is called. Not only is this process tedious to code, but it is also 
prone to errors. The purpose of the TC is two-fold: to eliminate the coding 
overhead and to automate the sequence as much as possible in order to eliminate 
coding errors.

	The TC is not available for use unless you specifically invoke it by 
using the TCOMP pseudo-op. If you want to use the TC, just specify TCOMP at the 
beginning of your source file. TCOMP loads the symbol table with special highly 
encoded macrox definitions of all the stack-based traps.

	Once you've activated the TC with TCOMP, you can then invoke any 
stack-based trap by specifying the name of the trap as an opcode and follow it 
with a list of parameters as operands like this:

	TrapName <tab> param1, param2,...,paramn [,=result]

Notice that TrapName is not preceded by an underscore character. This allows 
you to bypass the TC and manually invoke all of the traps by using the trap 
name preceded by an underscore.

	The list of parameters param1...paramn varies depending on the trap 
you're calling. The parameters in the list correspond exactly to the PASCAL 
definitions of the traps in Inside Macintosh. Some traps don't have any 
parameters, in which case you don't specify any. The contents of the parameters 
you specify are automatically pushed onto the stack for you by the TC. The size 
of the item pushed (byte, word, long) is also automatically taken care of for 
you by the TC.

	In some cases, you'll want to use the address of a symbol as a 
parameter instead of its contents. The TC allows you to do that by specifying 
an exclamation point character ! in front of the parameter. Note that ! is only 
allowed on parameters of size long.

	The =result item is only used on functions. If the trap returns a 
result on the stack, then it's a function and you have to specify where you 
want the result to be stored. In the case of functions, the TC automatically 
creates room on the stack for the function result before stacking any input 
parameters and pops the result off the stack after the trap returns and stores 
it in the result parameter you specify (again, taking care of sizing 
automatically.) The = before a result item is optional. It's only purpose is to 
improve readability of your code.

	All of this may sound complex, but it's really pretty easy to use. 
Examples are a better way to explain it, so...

AN EXAMPLE

	Here's an example of using the TC. We'll use the Menu Manager trap 
_NewMenu which has a PASCAL definition of:

	function NewMenu (menuID:INTEGER; menuTitle:Str255) : MenuHandle

Here's a code fragment using this trap:

			tcomp			turn on the trap compiler

	ourTitle	text	#"Example"	parameters we'll need
	ourMenu	equ	100
			a5sec
	MHandle	ds.l	1
			a5end

			NewMenu	#ourMenu,!ourTitle,=MHandle

This trap call would be expanded by the TC to the following sequence:

			subq.l	#4,sp
			move.w	#ourMenu,-(sp)
			pea	ourTitle,-(sp)
			dc.w	$A931
			move.l	(sp)+,MHandle

Notice that in this example we needed the address of the title so we prefixed 
ourTitle with !.

	Let's use the same trap for another example. Assume that this time we 
have computed the value of the menu ID and the address of the title string 
dynamically. Assume further that the menu ID is in register D1 and the title 
string address is in A2. We would then invoke the trap as follows:

			NewMenu	d1,a2,a0

Which would expand to:

			subq.l	#4,sp
			move.w	d1,-(sp)
			move.l	a2,-(sp)
			dc.w	$A931
			move.l	(sp)+,a0

Notice that this time we didn't specify the = to indicate a function result. 
This is perfectly acceptable but not as readable. Also notice that we stored 
the result in register A0 as opposed to MHandle.

A NAMING QUIRK

	There are two stack-based traps which have the same names as McAssembly 
opcodes: the QuickDraw traps Move and Line. To avoid conflicts, if you want to 
use the TC on these traps, be aware that they're renamed QDMove and QDLine in 
the TC. You have to use these new names if you want the TC to recognize these 
two traps.

WHAT TRAPS AREN'T RECOGNIZED

	The trap compiler doesn't contain definitions for the following traps 
(because they're register-based):

	Device Manager
	File Manager
	Memory Manager
	OS Event Manager
	OS Utilities
	Segment Loader

	In addition, only the following packages are supported:

	International
	Standard File
	Disk Initialization
	SCSI Manager
	List Manager
	Color Picker
	Script Manager
	ShutDown Manager

	(The trap compiler contains definitions for all of the stack-based Mac+ 
traps for the 128K ROM and Mac II color traps for the 256K ROM.)

USING IT WITH .PSM FILES

	There are naming conflicts between the names recognized by the TC and 
some equates in the .PSM files. In particular, some "routine selector" equates 
will cause conflicts. For example, SFGetFile is both a legal TC trap name and a 
routine selector equate in the PackMacs.PSM file. If you want to use the TC 
with the .PSM files, then you must activate it after you've included the .PSM 
files!. In other words, don't use TCOMP until after all of your includes. If 
you do this, then the symbols which are in both files will be forced to be trap 
compiler names. The duplicated symbols will no longer be available as equated 
values. Which is what you want, since if you're using the TC, then you won't 
need the routine selector equates.

**************************************************************************
			THE RESOURCE COMPILER
**************************************************************************


	McAssembly contains a built-in Resource Compiler which can assemble 
resource definitions. A two-character resource delimiter at the start of a 
source line identifies resource definitions. The delimiter sequence $$ starts a 
standard resource definition, a definition of a resource type that McAssembly 
knows how to interpret. The delimiter sequence [[ starts a user-defined 
resource definition, a definition of a resource type that McAssembly doesn't 
know how to interpret. The delimiter sequence ]] ends a user defined resource 
definition. Standard resource definitions don't require an ending delimiter 
because McAssembly knows where the resource definition ends from information 
you supply in the definition.

	The formats of the two types of definitions are as follows:

	$$ TYPE, ID, ATTR, NAME [<tab>] [;] [comment]
	<item list>

	or

	[[ TYPE, ID, ATTR, NAME [<tab>] [;] [comment]
	<code and/or data>
	]]


	TYPE is a four-character resource type. For standard definitions, it 
must be one that McAssembly recognizes. For a user-defined definition, it can 
be any four characters. ID is the resource ID number. ATTR specifies the 
attribute byte for the resource. NAME is the name string of the resource. ATTR 
and NAME are optional parameters and may be omitted, although you can't omit 
the ATTR if you want to specify a NAME. Here are two examples for a standard 
resource, one with all parameters specified, and one with ATTR and NAME 
omitted:

	$$ ALRT, 2, 0, alert no. 2

	$$ WIND, 1

	The item list is simply a list of items that make up the resource 
definition. McAssembly interprets each item in the list in a certain way. The 
types of items you specify in the list must correspond exactly with the types 
of items that McAssembly expects for that resource. If you specify an item of 
the wrong type or if you specify too many or too few items, you'll get syntax 
errors (many) on subsequent lines of the file. 

	Items in the item list appear at the beginning of subsequent source 
lines after the line containing the $$. The format of lines in the item list is 
as follows:

	item [, item, ...] [<tab>] [;] [comment]
	item [, item, ...] [<tab>] [;] [comment]
	etc... for as many lines as it takes to specify all items

As you can see, you have your choice of entering each item on its own source 
line, or of placing several items on one line, or a combination of either. 
McAssembly ignores all subsequent characters on the line after a tab or ; 
character and skips to the start of the next line for the next item in the 
list.

	There are several types of items. The type of each is marked in the 
descriptions of the formats for each standard resource. These types have the 
following meanings:

	bexp	an expression interpreted as a byte
	wexp	an expression interpreted as a word
	lexp	an expression interpreted as a long
	chrl	a four-character long
	str	a string

	bexp, wexp, and lexp items are numeric expressions and can be any legal 
McAssembly expression. In most cases, you don't have to worry about what size 
the expression is. In some cases you do, particularly in the bit maps, which 
McAssembly interprets as a sequence of longwords.

	Enter chrl items as a sequence of from one to four characters. If you 
specify fewer than four characters, then the item is left justified in a 32-bit 
long and padded on the right with spaces. Don't enclose the characters in 
quotation marks.

	You may enter strings in either of two ways. First, if your string 
contains no special characters or leading spaces you can just type the string. 
If it does contain special characters or leading spaces, you must enclose the 
string in quotation marks as "string".  (Any of the escape sequences allowed in 
TEXT strings are allowed in string.) If your string isn't enclosed in quotation 
marks, then you can continue the string to the start of the next line by ending 
the string with a \ character. Strings enclosed in quotes can't be continued to 
the next line. You can specify a null string (a string with a length of zero) 
with the vertical bar |.

	The code and/or data in a user-defined resource may be any combination 
of legal McAssembly instruction opcodes or pseudo-ops. The definition must end 
with the ]] delimiter or you'll get an error message.

STANDARD RESOURCE FORMATS

	What follows is a list of the standard resource types that McAssembly 
recognizes and the formats of the item lists for each. Each item in these 
formats appears on its own source line but that doesn't have to be the case. 
They're only shown that way here for clarity.

----------------------------------------------------------------------------

$$ ALRT,ID,ATTR,NAME
TOP		wexp	bounds rectangle:
LEFT		wexp
BOTTOM		wexp
RIGHT		wexp
DITL_LIST_ID	wexp	resc ID of item list
STAGES		wexp	see DLOG Mgr, IM, page 35

----------------------------------------------------------------------------

$$ BNDL,ID,ATTR,NAME
SIGNATURE		chrl	application's signature
VERS_DATA_RESC_ID	wexp	0 by convention
NO_RESC_TYPES		wexp	no. of BNDL resc types that follow:

For each resc type:
RESOURCE_TYPE		chrl	typically ICN# or FREF
NO_MAPPINGS_THIS_TYPE	wexp	no. of mappings that follow:

For each mapping:
LOCAL_ID	wexp
ACTUAL_ID	wexp


** Note: If you use the standard BNDL resource in a module, then McAssembly
automatically sets the bundle bit in the output file after the link is 
completed.

----------------------------------------------------------------------------

$$ CNTL,ID,ATTR,NAME
TOP			wexp	bounds rectangle:
LEFT			wexp
BOTTOM			wexp
RIGHT			wexp
INITIAL_VALUE		wexp	current value of control
VISIBLE			wexp	boolean
MAX_VALUE		wexp	maximum value of control
MIN_VALUE		wexp	minimum value of control
CTRL_DEFINITION_ID	wexp	resc ID of the definition function for
		   			the control type:
						0  simple button
						1  check box
						2  radio button
						8  add to use window's font
						16 scroll bar
REFCON			lexp	user defined value
TITLE			str	the control's title

----------------------------------------------------------------------------

$$ CURS,ID,ATTR,NAME
CURSOR_DATA_BYTES	lexp	eight longs of cursor image:
   "	lexp
   " 	lexp
   " 	lexp
   " 	lexp
   " 	lexp
   " 	lexp
   " 	lexp
CURSOR_MASK_BYTES	lexp	eight longs of cursor mask:
   " 	lexp
   " 	lexp
   " 	lexp
   " 	lexp
   " 	lexp
   " 	lexp
   " 	lexp
H_OF_HOT_SPOT		wexp	horizontal of the hot spot
V_OF_HOT_SPOT		wexp	vertical of the hot spot

----------------------------------------------------------------------------

$$ DITL,ID,ATTR,NAME
NO_ITEMS_IN_LIST	wexp	no. of items in this list:

For each item in the list:
HANDLE_HOLDER		lexp	placeholder for handle or pointer - normally 0
TOP			wexp	display rectangle (local coordinates):
LEFT			wexp
BOTTOM			wexp
RIGHT			wexp
ITEM_TYPE		bexp	type of the item:
					0   user defined (dialog only)
					4   std button control
					5   std check box control
					6   std radio button control
					7   defined in CTRL template
					8   static text
					16  editable text (dialog only)
					32  icon
					64  QuickDraw picture
					128 add to any of above to disable
ITEM	----			the actual item; contents of this field
				depend on item type as follows:
				If item type is, then content is:
  				 4,5,6	str	control title
  				 7	wexp	resc ID of template
  				 8,16	str	the text
  				 32,64	wexp	resc ID of ICON or PICT
   				 0	nil	empty (length = 0)

----------------------------------------------------------------------------

$$ DLOG,ID,ATTR,NAME
TOP			wexp	bounds rectangle:
LEFT			wexp
BOTTOM			wexp
RIGHT			wexp
WINDOW_DEFINITION_ID	wexp	the type of window:
					0  std doc wind or modeless dialog box
					1  alert box or modal dialog box
					2  plain box
					3  plain box with shadow
					4  doc window without size box
					16 rounded corner window
VISIBLE			wexp	boolean, initial state of dialog
GOAWAY			wexp	boolean, TRUE means window has a close box
REFCON			lexp	user defined value
RESC_ID_OF_ITEM_LIST	wexp	resc ID of the DITL for this dialog
TITLE			str	the dialog's title (0 length string if modal 	
				dialog box)

----------------------------------------------------------------------------

$$ FREF,ID,ATTR,NAME
FILETYPE		chrl	typically APPL
LOCAL_ID_FOR_ICON_LIST	wexp
FILENAME		str	filename that should follow the file
		    			to a new disk (null string if none) 

----------------------------------------------------------------------------

$$ ICON,ID,ATTR,NAME
(32) ICON_BYTE_LONGS	lexp	icon bit map - 32 longs:
...
...

----------------------------------------------------------------------------

$$ ICN#,ID,ATTR,NAME
(32) ICON1_BYTE_LONGS	lexp	icon bit map - 32 longs:
...
...
(32) ICON2_BYTE_LONGS	lexp	icon bit map mask - 32 longs:
...
...

----------------------------------------------------------------------------

$$ MENU,ID,ATTR,NAME
WIDTH_HOLDER		wexp	0 - placeholder for menu width
HEIGHT_HOLDER		wexp	0 - placeholder for menu height
STD_MENU_PROC_HOLDER	lexp	normally 0
ENABLE_MASK		lexp	bit 0 set if menu enabled,
		  		bit 1 set if menu item 1 enabled,
		  		bit 2 set if menu item 2 enabled,
		  		etc...
MENU_TITLE		str	the menu's title
NUMBER_MENU_ITEMS	wexp	number of items in the menu:

For each menu item:
MENU_ITEM		str	the text of the item
ICON_NUMBER		bexp	0 = none, ICON'S resc ID = ICON number + 256
KEYBD_EQUIV		bexp	equivalent kybd char code, 0 = none
MARKING_CHAR		bexp	marking char code, 0 = no mark
TEXT_STYLE		bexp	text style of the item:
					bit 0 = bold
					bit 1 = italic
					bit 2 = underline
					bit 3 = outline
					bit 4 = shadow
					bit 5 = condense
					bit 6 = extend

----------------------------------------------------------------------------

$$ PAT ,ID,ATTR,NAME
PATTERN_BYTES	lexp	two longs:
   "		lexp

----------------------------------------------------------------------------

$$ PAT#,ID,ATTR,NAME
NO_OF_PATTERNS		wexp	the number of patterns in the list:

For each pattern:
PATTERN_BYTES		lexp	two longs:
   "			lexp

----------------------------------------------------------------------------

$$ STR ,ID,ATTR,NAME
STRING			str

----------------------------------------------------------------------------

$$ STR#,ID,ATTR,NAME
NO_OF_STRINGS		wexp	the number of strings in the list:

For each string:
STRING			str

----------------------------------------------------------------------------

$$ WIND,ID,ATTR,NAME
TOP			wexp	bounds rectangle:
LEFT			wexp
BOTTOM			wexp
RIGHT			wexp
WINDOW_DEFINITION_ID	wexp	window type:
					0  std doc window or modeless dialog 	
					box
					1  alert box or modal dialog box
					2  plain box
					3  plain box with shadow
					4  doc window without size box
					16 rounded corner window
VISIBLE			wexp	boolean, initial state of window
GOAWAY			wexp	boolean, TRUE means window has a close box
REFCON			lexp	user defined value
TITLE			str	the window's title

----------------------------------------------------------------------------

[[ XXXX,ID,ATTR,NAME	user defined resource
<DATA/CODE>		whatever you want
...
]]			don't forget the ender!

----------------------------------------------------------------------------

**************************************************************************
			LINKING
**************************************************************************

	McLink is the linker portion of the McAssembly program. McLink links 
together .REL files produced by McAssembly and stores the result in a resource 
file. Depending on the contents of the .REL files, the resulting resource file 
is either a pure resource file or an executable application.

	(McAssembly can't link object files which are in the MDS or MPW 
formats. The reverse is also true. However, McAssembly can generate MPW format 
object files, and a utility is provided to those who register that will convert 
McAssembly object files to MDS object files.)

	The file you specify to McLink is actually a link specification file. 
It contains the names of the files to be linked and the name of the resulting 
output file. The specification file has the following format (each filename is 
on a separate line):

	* Lines starting with an asterisk are comments and are ignored.
	...
	input .REL filename 1
	input .REL filename 2
	...
	* Lines grouped by [...] are used to consolidate user-defined
	* 	resources which are split up into several source modules
	* 	into one resource. As follows...
	[
	input .REL filename 3
	input .REL filename 4
	...
	]
	% input resource filename n
	% input resource filename n+1
	...
	* Lines starting with an '@' are path specifiers - they specify an HFS
	* 	path to use to access all subsequent files
	@ pathname
	...
	/output filename

The input files must be either McAssembly .REL files or resource files. The % 
character must be the first character of lines containing resource filenames to 
differentiate them from .REL files. If an input filename doesn't end in .REL 
and it's not a resource file, McLink adds .REL to the name before it tries to 
open the file. The output filename must be the last filename in the list and 
must be preceded by a slash character.

	Resource files are handled as follows: McLink copies all resources in 
the resource file to the linked output file. If a resource in the resource file 
is the same as a resource defined in a .REL file, the resource file copy will 
replace the .REL file copy in the output file. If a BNDL resource is copied, 
the output file's bundle bit is set.

	There are only two aspects of ordering that you must follow: 1.) the 
first data item in the first file that's linked must be the starting 
instruction of the program, and 2.) all resources must be linked after all code 
and/or data. If you attempt to link code after a resource has been linked you 
get an error message.

**************************************************************************
			SEGMENTING
**************************************************************************

	McAssembly lets you divide up your application into segments. To 
implement segmenting, you have to do two things: 1.) specify what routines in a 
particular module may be called from other segments, and 2.) specify the 
partitioning of the code into segments, i.e., what modules are in what 
segments. Item 1 is accomplished through the use of the JTBL pseudo-op and 
allows McLink to construct the jump table containing an entry for every 
cross-segment accessible routine. Item 2 is accomplished by a SEGMENT COMMAND 
LINE in your link specification file and tells McLink how to break up the code 
into segments. The JTBL pseudo-op is described earlier and the segment command 
line description follows.

	The Segment Command Line is a special command line in the link 
specification file. It has the following syntax:

	$ [P] [L]

The $ character tells the linker that this line is not the name of a file to be 
linked but is the start of a new segment. The segment command line writes all 
modules linked so far to the output file as one segment and groups all 
subsequent modules (until another segment command line) into a new segment. The 
P and L parameters specify the attributes of the new code segment. P specifies 
that the segment is to be "preloaded" and L specifies that the segment is to be 
"locked." The default for both of these parameters is "not preloaded" and "not 
locked." (Don't specify a segment command line for the first segment. McLink 
defaults the attributes for segment number one to "preloaded," "locked," and 
"purgeable.")

	Here's an example link specification file for an application that 
contains four code segments:

	MAIN
	$
	SEG2A
	SEG2B
	$ P
	SEG3
	$ L P
	SEG4
	/MAIN.APPL

In this example, MAIN is in segment one, SEG2A and SEG2B in segment two, SEG3 
in segment three, and SEG4 in segment four. All segments are purgeable; 
segments one, three and four are to be preloaded; and segments one and four are 
locked. The resulting application program is placed in the file MAIN.APPL.

**************************************************************************
			JOB FILES
**************************************************************************

	The File menu Run job choice in McAssembly operates on a Job 
Specification File. A job specification file contains a list of filenames to be 
assembled and linked to form an output file. By using a job specification file, 
you eliminate assembling each file separately and invoking the linker to link 
them.

	The format of a job specification file is a link specification file 
whose filenames have no suffixes (.ASM or .REL). In fact, a job specification 
file can be used as a link specification file, providing it specifies an output 
file in its last filename line. Here's an example of a job specification file:

	* This is a comment line
	* Assemble the file X.ASM if necessary:
	X
	* Assemble the file Y.ASM if necessary:
	Y
	* Assemble the file Z.ASM if necessary:
	Z
	* Put the linked X.REL, Y.REL and Z.REL files into the
	*	output file XYZ:
	/XYZ

	To understand what the job control manager does for this file, 
understand first that a job is run in two phases, an assembly phase and a link 
phase. The assembly phase assembles the files and the link phase links the 
resulting .REL files.

	During the assembly phase, the job control manager ignores any line in 
the specification file which starts with any of the characters *, $, or / or 
which is a blank line. These are comment lines and link control lines which 
have no meaning in assembly. Any other lines are assumed to contain a 
non-suffixed filename which is a candidate for assembly. For example, the first 
thing the job control manager does for this job file is to skip the first two 
lines because they're comment lines. It then operates on the line X. The job 
control manager looks to see if X.ASM is on the disk. Let's assume for the 
purposes of this example that X.ASM isn't on the disk. In this case, the job 
control manager assumes that X.REL exists and that you don't want to reassemble 
it. So the specification file line containing X is ignored.

	The next line is examined similarly. Let's assume the converse here - 
that Y.ASM does exist. The job control manager assembles Y.ASM if either one of 
the following two conditions is met: 1.) there is no Y.REL file on the disk, or 
2.) the existing copy of Y.REL is out-of-date. (It's out-of-date if the 
modification date of Y.REL is earlier in time than the modification date of 
Y.ASM.) In either of these two cases, Y.ASM is assembled, creating a new copy 
of Y.REL. If Y.REL is up-to-date, then the specification line containing Y is 
skipped and no assembly is performed.

	Having disposed of the Y file line, the job control manager goes on to 
the Z file line. A similar analysis goes on as above and Z.ASM is assembled if 
necessary.

	Finally, the last line, /XYZ, is examined. The job control manager 
recognizes this as an output file specification line for the linker, so the 
linker is invoked. This ends the assembly phase of the job and begins the link 
phase.

	In the link phase, the linker links the files using the job 
specification file as the link specification file. After the link is complete, 
the job is done and control returns to the top level of McAssembly.

	If the /XYZ line doesn't exist in the job file, then the job control 
manager assumes that no link is desired and skips the linker phase of the job. 
This allows you to use job files for just assemblies.

**************************************************************************
			68020 ADDRESSING MODES
**************************************************************************

Here are the syntaxes for the new 68020 address modes, where

	bd		is the base displacement
	An or PC	is the base register
	Rn*s		is the index register and s = a scale factor of 1,2,4,8
				(scale defaults to 1 if omitted)
	od		is the outer displacement

(The spaces in the following aren't necessary - they're just there to
visually show the components which may be specified or omitted.)


	( bd,An ,Rn*s   )	addr reg indirect with base displacement
	(    An ,Rn*s   )	*** old 68000 address mode
	( bd,An         )
	(    An         )	*** old 68000 address mode

	([bd,An],Rn*s,od)	addr reg memory indirect, post-indexed
	([   An],Rn*s,od)
	([   An]     ,od)
	([   An]        )
	([bd,An]     ,od)
	([bd,An]        )

	([bd,An,Rn*s],od)	addr reg memory indirect, pre-indexed
	([   An,Rn*s],od)
	([   An]     ,od)
	([   An]        )
	([bd,An]     ,od)
	([bd,An]        )

	( bd,PC ,Rn*s   )	PC indirect with base displacement
	(    PC ,Rn*s   )
	( bd,PC         )
	(    PC         )

	([bd,PC],Rn*s,od)	PC memory indirect, post-indexed
	([   PC],Rn*s,od)
	([   PC]     ,od)
	([   PC]        )
	([bd,PC]     ,od)
	([bd,PC]        )

	([bd,PC,Rn*s],od)	PC memory indirect, pre-indexed
	([   PC,Rn*s],od)
	([   PC]     ,od)
	([   PC]        )
	([bd,PC]     ,od)
	([bd,PC]        )

Notice that you can omit any of the address components except for the
base register component by simply not typing it. If you want to suppress
the base register, then specify either ZA or ZP for the An and PC components
of the address respectively. For example,

	(bd,ZP,Rn)	will suppress the PC base register

The base and outer displacements may be either word or long values.
McAssembly uses whichever size is appropriate based on the symbol's value.
You can't specify a particular size. Also, base and outer displacements
must be absolute symbols, except in the PC memory indirect modes, in which
case the base displacement must be a relocatable value.

**************************************************************************
			FILE SUFFIXES
**************************************************************************

	McAssembly requires certain suffixes on filenames as follows: (These 
can be in any combination of upper or lower case.)

	.asm	assembler source files
	.rel	assembler object files
	.lst	assembler listing files
	.psm	assembler packed symbol files
	.lnk	link specification file
	.job	job specification file or link specification file
	.map	linker listing output file
	.sym	binary symbol table output by the linker for use by McBug

**************************************************************************
			TRANSFER MENU NAMES
**************************************************************************

	The filenames in the Transfer Menu are changeable by the user using 
ResEdit. It works like this: Any STR resource in the McAssembly file with an ID 
of 1000 or greater is interpreted by McAssembly as a filename to be added to 
the Transfer Menu. You can edit or delete the supplied filenames, or add as 
many of your own as you like. The following special details apply to this 
process:

	*	A filename consisting of only a dash '-' generates a disabled
			line of dashes.
	*	A '/' before a character will make that character a command
			key equivalent for the transfer to that file.
	*	A '<' before a B,I,U,O, or S will make the style of the menu
			item bold, italic, underline, outline, or shadow
			respectively.
	*	If the file isn't in the same folder as McAssembly, then you
			must specify a full HFS pathname as in
			'Volname:Folder:Filename'.
	*	A filename can't be longer than 31 characters.

**************************************************************************
			MPW FORMAT
**************************************************************************

	McAssembly can create object files in the MPW format. The linker can't 
link them, but you can link them with the MPW linker. MPW object files will 
have the suffix '.o.' as opposed to the normal '.rel'.

	There are two special assembler pseudo-ops in MPW mode. You can use 
them in normal McAssembly mode, but they'll have no effect on the output files. 
These pseudo-ops and their descriptions are: 

	MAIN

	Identifies a module as being the main code and data module in the 
application. This causes two things to happen: 1.) The first instruction in the 
module will be the first instruction executed when the resulting linked 
application is executed, and 2.) Any A5SEC data in the module is guaranteed to 
be located immediately below A5. (This data placement is discussed in more 
detail below.)

	(In McAssembly, a "module" is equivalent to a source file. This is 
different than the MPW definition of a module, which allows any number of 
modules to be contained in one source file.)

	SEG	["<segment name>"]

	Allows you to control the segmentation of your program. Only the last 
seg statement in a source file is effective. It causes all of the code 
generated by that file to be placed in a segment named segment name. Code which 
resides in any particular segment doesn't have to be linked consecutively - the 
MPW linker figures out what goes where and collects all segment code together 
regardless of what order the files are linked in. If you don't use a seg 
statement in a file or use a seg without a segment name then all of the code in 
the file is placed in a segment named Main by the  linker.

	(Again, this is slightly different than the MPW convention, which 
allows code in any one source file to be placed into any number of segments.)

RESTRICTIONS

	Just as there are some things you can do in the MPW assembler that you 
can't do in McAssembly, there are also some McAssembly features that can't be 
implemented with the MPW object format. Here's what you can't do in MPW mode:

	1.) The pseudo-ops A5OFF, FSIGN, and FTYPE are illegal in MPW mode.

	2.) None of the resource compiling capabilities can be used.

	3.) In McAssembly, you can branch to an externally defined symbol using 
the Bcc, BSR, and DBcc instructions. You can't do that in MPW. You have to use 
equivalent JSR and JMP instructions instead.

A5 DATA STORAGE

	The MPW linker has a slightly different perspective of A5 data 
allocation than MDS had - it's entirely under your control. This means that the 
linker has no provisions for allowing for the usual $100 bytes of QuickDraw 
global storage on top of your own A5 data. If your programs rely on this (and 
they do if they do an InitGraf !-4(A5) when they start up!), then you have to 
allocate this area specifically yourself. You can do it very simply like this

		a5sec
	<your own global variable definitions>
		ds.b	grafSize	QuickDraw's space
		a5end

but there are two important restrictions for this to work properly:

	1.) The grafSize bytes of A5 storage must be defined in the main module 
(the source file containing the main pseudo-op.) If it's not in the main 
module, then the linker will not necessarily place it immediately below A5.

	2.) The grafSize bytes of A5 storage must be the last A5 storage item 
defined in the main module. In other words, if you have several A5SEC's in your 
main file, then make sure that the grafSize bytes are the last A5SEC item in 
the file. (This is because McAssembly allocates A5 variables in reverse order 
of how they appear in the file - the first A5 variable is the lowest in memory, 
and the last is highest in memory.)

	(Notice that grafSize, which is defined in the QuickEqu system file, is 
only $CE bytes, not $100. GrafSize is all that's actually required. I think the 
$100 was just used for historical reasons as an arbitrarily large enough 
number.)

**************************************************************************
			USER-DEFINABLE .MAP FILES
**************************************************************************

	The McAssembly linker menu contains an option to save link .MAP files 
in a user-definable format. This is accomplished by the use of a resource 
containing the user-supplied formatting code. This resource is type UMAP, ID 
128. If a .MAP file has been requested, and if the user .MAP file format is 
selected, then the linker communicates with the UMAP resource code to 
accomplish the writing of symbol table information to the .MAP file.

	The default user .MAP file format is an enhanced MDS format, and has 
been designed to work with Steve Jasik's debugger. It should probably also work 
with TMON. The source code for the UMAP resource is provided to all registered 
users so it can easily be modified to support other .MAP formats.

**************************************************************************
			CONFIGURATION RESOURCES
**************************************************************************

	The following resources affect McAssembly's operation, and may be 
changed to whatever you like:

STR,128	=	The four-character creator string for all text files created
		by McAssembly. For example, change this to 'QED1' if you use
		the QUED editor.

STR,129 =	A string which is sent to the printer before every print job.
		Change this to whatever your printer likes to see.

